import Details from 'components/Details';
import PartnerContentLink from 'components/PartnerContentLink';

# Markdown (MDX)

Especially for sites where the content varies significantly by locale and may require a different structure, it can be helpful to use Markdown or [MDX](https://mdxjs.com) to provide your localized content. To consume this content in a Next.js app, you can use the [`@next/mdx`](https://nextjs.org/docs/app/building-your-application/configuring/mdx) package, which allows you to import and render MDX content.

While you can create entire pages using `page.mdx` files, in an app that uses [the `[locale]` segment](/docs/getting-started/app-router), it can be beneficial to import localized MDX content based on the user's locale into a single `page.tsx` file.

After following the [setup instructions for `@next/mdx`](https://nextjs.org/docs/app/building-your-application/configuring/mdx), you can consider placing your localized MDX files next to a page that will render them:

```
src
└── app
    └── [locale]
        ├── page.tsx
        ├── en.mdx
        └── de.mdx
```

Now, in `page.tsx`, you can import the MDX content based on the user's locale:

```tsx filename="src/app/[locale]/page.tsx"
import {notFound} from 'next/navigation';

export default async function HomePage({params}) {
  try {
    const Content = (await import(`./${params.locale}.mdx`)).default;
    return <Content />;
  } catch (error) {
    notFound();
  }
}
```

In this example, an MDX file might look like this:

```mdx filename="src/app/[locale]/en.mdx"
import Portrait from '@/components/Portrait';

# Home

Welcome to my site!

<Portrait />
```

Components that invoke hooks from `next-intl` like `useTranslations` can naturally be used in MDX content and will respect the user's locale.

<Details id="rich-text">
<summary>Is MDX required to format rich text?</summary>

Not at all! The built in message formatting of `next-intl` supports [rich text syntax](/docs/usage/messages#rich-text), which can be used to provide formatting, and to embed React components within messages.

MDX is best suited for cases where content varies significantly by locale. If all you're looking for is rich text formatting, the built-in message formatting may be an easier choice.

</Details>

<Details id="remote-files">
<summary>Can I load MDX content from a remote source?</summary>

Especially if you'd like to allow translators to collaborate on MDX files, you can consider uploading them to a translation management system like <PartnerContentLink href="https://crowdin.com/">Crowdin</PartnerContentLink>.

In this case, you can fetch the MDX content dynamically from within a page and parse it using a package like [`next-mdx-remote`](https://nextjs.org/docs/app/building-your-application/configuring/mdx#remote-mdx).

Note that MDX compiles to JavaScript and is dynamically evaluated. You should be sure to only load MDX content from a trusted source, otherwise this can lead to [arbitrary code execution](https://en.wikipedia.org/wiki/Arbitrary_code_execution).

</Details>
